Skip to main content

VIDconnect

VIDconnect implements the OpenID connect identity protocol, in particular the OpenID connect Self-Issued OpenID Provder standard. The protocol flow and a detailed descripion can be found in section OpenID Connect User Authentication Flow.

Register your Entity​

In order to interact with VIDconnect you need to register your entity. An entity represents a party that will be registered at VIDconnect. This entity will hold the OpenID client information.

important

VIDconnect is an independent service and requires the registration of its own entity, independently from VIDcredentials.

If you are interested in using VIDconnect, please contact the VIDchain support team support@vidchain.org for your entity creation in VIDconnect.

To register an entity, the following information have to be provided:

  • redirect_uri: This URL defines the location where the OIDC Provider should redirect the user after the authentication flow is finished. More than one URL can be provided for testing purposes.
  • (optional) logo : This optional attribute defines the image that will appear when user is logging in (QR website).
  • (optional) scope: Specify which kind of credentials you want to allow presenting: email, phone, verifiableId. By default, any generic Verifiable Credential is valid if you do not specify otherwise.

With this information, Validated ID is ready to create your entity and provide you back the access details:

  • client_id : The client id is a string to uniquely identify your client when making calls to the OIDC provider.
  • client_secret: The client secret is used to authenticate the client to OIDC provider.

Integrate your site to VIDconnect​

Once you are provided with your client_id and client_secret you are ready to start the integration.

The flow basically consists on:

  1. Redirecting the user from your website to VIDconnect. The user will interact with VIDconnect either through scanning a QR code or, if the user is navigating in a mobile browser, it will be automatically be redirected to folllow the process with VIDwallet app.
  2. The user will select with which DID wants to be authenticated and present any credential requested.
  3. VIDconnect will validate the presentation of the ownership of the DID and the verifiable presentation validity. If success, VIDconnect will provide a code to your redirect_uri.
  4. With this code received via callback, you are ready to request the JWT that contains the information presented by the user, either the did or a verifiable presentation.
  5. Use the information within the JWT to validate your business logic rules.

How to redirect the user to VIDconnect​

As integrator you now own an openID client for VIDconnect. With this client you need to perform a request to the following URL https://staging.vidchain.net/oauth2/auth. This endpoint will redirect your client to https://staging.vidchain.net/oauth2/login where VIDconnect login QR code will be shown. See more details about this endpoint at Redirect User to VIDconnect OpenAPI Specification.

Retrieve the ID Token​

Once the user has authenticated, the openID (you as integrator) will receive a code in a previously specified callback_url. With this code, the client_id and the client_secret, you will be able to retrieve user's information. You can retrieve the information through https://staging.vidchain.net/oauth2/token which will provide you an id_token. This token is a JWT which contains user's information (did, verifiable presentation...).

You have to retrieve the information provided from vp field found in JWT payload. This is a dummy example of the payload of a decoded id_token:

{
  ...
  "did": "did:ethr:0x733D178303Efdf2155336728f7d3CA1e7009a4BB",
  "vp": {
    "@context": [
      "https://www.w3.org/ns/did/v1"
    ],
    "proof": {
      "created": "2022-09-26T11:49:57.000Z",
      "jws": "eyJhbGciOiJFUzI1NkstUiIsInR5cCI6IkpXVCJ9.eyJpYXQi...X19.8wYnV6c8DRcXhArxFnwZOoNTMIsNMU_GW52puWfNkXXNRwu5ckoO7TufZYEDaVhesHqkFF8bYJcoNf7cbHA0GQE",
      "proofPurpose": "assertionMethod",
      "type": "EcdsaSecp256k1Signature2019",
      "verificationMethod": "did:ethr:0x733D178303Efdf2155336728f7d3CA1e7009a4BB#key-1"
    },
    "type": "VerifiablePresentation",
    "verifiableCredential": [
      {
        "@context": [
          "https://www.w3.org/2018/credentials/v1",
          "https://api.vidchain.net/credentials/vid-google/v1"
        ],
        "credentialStatus": {
          "id": "https://dev.vidchain.net/api/v1/revocation/credential-status/status-list/100/credential/724",
          "statusListCredential": "https://dev.vidchain.net/api/v1/revocation/status-list/100",
          "statusListIndex": "724",
          "type": "RevocationList2021"
        },
        "credentialSubject": {
          "email": "example@gmail.com",
          "id": "did:ethr:0x733D178303Efdf2155336728f7d3CA1e7009a4BB",
          "image": "https://lh3.googleusercontent.com/a-/ACNPEu8x95NzH16EsC18_cHvc2z4A=s40-b",
          "lastName": "Smith",
          "name": "Bob"
        },
        "id": "https://api.vidchain.net/api/v1/schemas/2393",
        "issuanceDate": "2022-09-20T07:48:10.000Z",
        "issuer": "did:ethr:0x078D7c2922E3f95A35A22C54696D8870b857C3f9",
        "proof": {
          "created": "2022-09-20T07:48:10.000Z",
          "jws": "eyJhbGciOiJFUzI1NksiLCJraWQiOiJkaWQ6ZXRocjoweDA3OEQ3YzI5MjJFM2Y5NUEzNUEyMkM1NDY5NkQ4ODcwYjg1N0MzZjkja2V5cy0xIiwidHlwIjoiSldUIn0.eyJpYXQ...bCJdfX0.heEE7Vcx2cCMl2zYdhxSzKEr7ZbvEUCHrDzKE-TL1WGISaO0mzyxwZOJdlbqKDVv2FqPsDnkHCSDuvXd3wJR3g",
          "proofPurpose": "assertionMethod",
          "type": "EcdsaSecp256k1Signature2019",
          "verificationMethod": "did:ethr:0x078D7c2922E3f95A35A22C54696D8870b857C3f9#keys-1"
        },
        "type": [
          "VerifiableCredential",
          "VerifiableIdCredential",
          "EmailCredential",
          "VidGoogleCredential"
        ]
      }
    ]
  }
}

See more details about this request under Retrieve OIDC ID Token VIDconnect OpenAPI specification.

Example setup of an OpenID Connect Client​

This section details the example configuration of an OpenID client using Typescript and the JSO client:

import { JSO, Popup } from "jso";

const nonce = utils.randomString(24);
const state = utils.randomString(24);

let configFile = {
  client_id: config.CLIENT_ID,
  client_secret: config.CLIENT_SECRET,
  token: config.IDENTITY_PROVIDER + "/oauth2/token",
  authorization: config.IDENTITY_PROVIDER + "/oauth2/auth",
  redirect_uri: config.REDIRECT_CALLBACK,
  scopes: {
    request: ["openid", "offline"],
    require: ["openid", "offline"],
  },
  response_type: "code",
  debug: true,
};

this.client = new JSO(configFile);

VIDchain Integration Examples​

More integration examples can be found on the public GitHub repository demonstrating for example the interaction with VIDconnect or VIDcredentials.